Docs: Add extended quickstart and installation guides (release + source) #2388

yiseungmi87 · 2025-12-18T02:20:45Z

This PR introduces improved documentation for new users of SystemDS:

Added

quickstart_extended.md - Overview page linking installation and execution docs
release_install.md - Clean, updated installation guide for release users
source_install.md - Updated guide for building SystemDS from source
run_extended.md - Comprehensive execution guide (local, Spark, federated)
run.md- Slightly modified

Scope

Documentation-only changes
No changes to SystemDS code or runtime behavior
Existing run.md is intentionally left for compatibility

Purpose

These changes provide clearer onboarding for new SystemDS users and consolidate documentation into a consistent structure.

Let me know if adjustments are desired before merging.

janniklinde

Thank you @yiseungmi87 for the good first PR, it seems to be quite clear and understandable so far.

I did not manage to set up SystemDS for Ubuntu by only following your guide (which should be the goal of the install guide) so please have a look into that. You can use a clean docker image to follow your guide and identify possible points of failure. Similarly, please check that for the other operating systems no such weak points exist (if you have windows, maybe try the setup on a new user). Also, I realized that when cloning SystemDS source code via GitHub Desktop on Windows, it might get stuck in the cloning process so we should provide a solution for that (e.g. use 'git' CLI for cloning rather than the app). So far, I have not tested the install for Windows / macOS but will do so once my current comments are resolved.

docs/site/release_install.md

docs/site/run_extended.md

docs/site/source_install.md

yiseungmi87 · 2025-12-29T02:54:23Z

Thanks again for the detailed feedback @janniklinde !

In addition to the changes in this PR, I verified the guides end-to-end on clean OS environments (Windows, Ubuntu, Mac).
Following only the Quickstart and installation guides, I was able to successfully complete the setup from installation through running the basic Hello World example on all tested systems.

Also, I’ve addressed the remaining minor issues such as markdown rendering issue or duplicate explanations.

Happy to adjust further if anything is still unclear or fails in your setup.

janniklinde

Thank you for the improvements @yiseungmi87. I left you some more feedback on where you could further refine the quickstart guide

docs/site/release_install.md

docs/site/source_install.md

docs/site/run_extended.md

yiseungmi87 · 2026-01-19T12:43:25Z

Hi, thanks a lot for the feedback! @janniklinde

I’ve updated the PR to reflect all points mentioned so far.

Regarding the note that this file feels like a clone of docs/site/install.md: that makes sense. The changes here are mainly meant as clarifications and fixes to the existing install guide, not as a separate alternative. So, what I understood is that the right next step would be to apply these changes directly to install.md and drop the separate file.

Before doing that, I just wanted to double-check that this approach is what you meant.

Thanks again!

janniklinde

Thanks again for your contribution @yiseungmi87 and sorry for the late response. The install instructions now seem to work. I noticed that your references are sometimes inconsistent (sometimes you refer to the html and sometimes to md).

Please replace the existing files (install.md and run.md) and double check the links/references. Also, the old run.md contains instructions for using Intel MKL native instructions. Is there a specific reason you left that out?

Finally, for this guide to be accessible as html, we require the header (like in the old install.md). When these issues are addressed, I think we are ready to merge.

docs/site/run_extended.md

docs/site/source_install.md

yiseungmi87 · 2026-01-27T10:40:21Z

Thanks for the feedback!
I’ve now merged the extended guides into the existing install.md and run.md.
All links and references were updated accordingly.
Please let me know if anything still looks off.

janniklinde

Thank you for the updates and overall contribution @yiseungmi87, with this PR your DIA project is successfully completed. I left some minor notes for us to fix before merging. We will take it from here.

janniklinde · 2026-01-30T08:31:54Z

docs/site/release_install.md

+(Optional but recommended) To make SystemDS available in new terminals, add the following lines to your shell configuration (e.g., ~/.bashrc or ~/.profile):
+```bash
+export SYSTEMDS_ROOT=/absolute/path/to/systemds-<VERSION>
+export SYSTEMDS_JAR_FILE=$(find "$SYSTEMDS_ROOT" -maxdepth 1 -type f -name "systemds-*.jar" | head -n 1)


Putting this line into .bashrc or .profile is usually bad practice because this command then runs every time you start a new terminal. Putting a path like /absolute/path/to/systemds-<VERSION>-bin/systemds-<VERSION>.jar would be preferred.

janniklinde · 2026-01-30T08:39:07Z

docs/site/release_install.md

+Hello World!
+```
+
+On some Ubuntu setups (including clean Docker images), running SystemDS directly may fail with `Invalid or corrupt jarfile hello.dml` Error. Ensuring that `SYSTEMDS_JAR_FILE`points to the SystemDS JAR shipped with the release resolves this issue.


Can be removed because the manual explicitly states to set SYSTEMDS_JAR_FILE -> redundant

janniklinde · 2026-01-30T08:41:19Z

docs/site/quickstart_extended.md

+
+If you simply want to *use* SystemDS without modifying the source code, the recommended approach is to install SystemDS from an official Apache release.
+
+**Full Release Installation Guide:** [SystemDS Install from release](https://apache.github.io/systemds/site/release_install.html)


Name like title of release_install.

janniklinde · 2026-01-30T08:41:59Z

docs/site/quickstart_extended.md

+
+If you plan to contribute to SystemDS or need to modify its internals, you can build SystemDS from source.
+
+**Full Source Build Guide:** [SystemDS Install from source](https://apache.github.io/systemds/site/source_install.html)


Name like title from source_install and update reference because it's now called install.md

Docs: extended quickstart and install/run improvements

4843d2f

github-project-automation bot added this to SystemDS PR Queue Dec 18, 2025

github-project-automation bot moved this to In Progress in SystemDS PR Queue Dec 18, 2025

janniklinde reviewed Dec 18, 2025

View reviewed changes

docs/site/release_install.md Outdated Show resolved Hide resolved

docs/site/release_install.md Show resolved Hide resolved

docs/site/run_extended.md Outdated Show resolved Hide resolved

docs/site/source_install.md Outdated Show resolved Hide resolved

docs: adress os-specific install issues and further changes

c72c6bd

janniklinde reviewed Dec 29, 2025

View reviewed changes

docs: remove redundant and fix CLI usage and JAR resolution

9bcd1c0

janniklinde reviewed Jan 26, 2026

View reviewed changes

docs/site/run_extended.md Outdated Show resolved Hide resolved

docs/site/source_install.md Outdated Show resolved Hide resolved

docs: merge extended guides into existing install and run docs

c0bcf58

janniklinde reviewed Jan 30, 2026

View reviewed changes


		If you simply want to use SystemDS without modifying the source code, the recommended approach is to install SystemDS from an official Apache release.

		Full Release Installation Guide: [SystemDS Install from release](https://apache.github.io/systemds/site/release_install.html)


		If you plan to contribute to SystemDS or need to modify its internals, you can build SystemDS from source.

		Full Source Build Guide: [SystemDS Install from source](https://apache.github.io/systemds/site/source_install.html)

Docs: Add extended quickstart and installation guides (release + source) #2388

Are you sure you want to change the base?

Docs: Add extended quickstart and installation guides (release + source) #2388

Conversation

yiseungmi87 commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Added

Scope

Purpose

Uh oh!

janniklinde left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yiseungmi87 commented Dec 29, 2025

Uh oh!

janniklinde left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yiseungmi87 commented Jan 19, 2026

Uh oh!

janniklinde left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

yiseungmi87 commented Jan 27, 2026

Uh oh!

janniklinde left a comment

Choose a reason for hiding this comment

Uh oh!

janniklinde Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

janniklinde Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

janniklinde Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

janniklinde Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yiseungmi87 commented Dec 18, 2025 •

edited

Loading